home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 January: Mac OS SDK / Dev.CD Jan 99 SDK1.toast / Development Kits / Mac OS USB DDK_v1.0.1 / Examples / PrinterClassDriver / TradDriverLoaderLib.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-09-03  |  10.4 KB  |  232 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        TradDriverLoaderLib.h
  3.  
  4.     Contains:    C interface for the pseudo-DriverLoaderLib for 'DRVR's.
  5.  
  6.     Version:    xxx put version here xxx
  7.  
  8.     Written by:    Quinn "The Eskimo!"
  9.  
  10.     Copyright:    © 1996, 1998 by Apple Computer, Inc., all rights reserved.
  11.  
  12.     File Ownership:
  13.  
  14.         DRI:                Craig Keithley
  15.  
  16.         Other Contact:        xxx put other contact here xxx
  17.  
  18.         Technology:            USB Drivers
  19.  
  20.     Writers:
  21.  
  22.         (CJK)    Craig Keithley
  23.  
  24.     Change History (most recent first):
  25.  
  26.       <USB2>     5/28/98    CJK        change file creater to 'MPS '
  27.     You may incorporate this sample code into your applications without
  28.     restriction, though the sample code has been provided "AS IS" and the
  29.     responsibility for its operation is 100% yours.  However, what you are
  30.     not permitted to do is to redistribute the source as "DSC Sample Code"
  31.     after having made changes. If you're going to re-distribute the source,
  32.     we require that you make it clear in the source that the code was
  33.     descended from Apple Sample Code, but that you've made changes.
  34. */
  35.  
  36. #include <Types.h>
  37. #include <Devices.h>
  38.  
  39. #ifdef __cplusplus
  40. extern "C" {
  41. #endif
  42.  
  43. ///////////////////////////////////////////////////////////////////////////
  44.  
  45. // The following routines are implemented with semantics virtually identical
  46. //  to those found in DriverLoaderLib.  You should look in
  47. //  "Designing PCI Cards and Drivers for Power Macintosh Computers" for
  48. //  documentation.  You can FTP an electronic copy from:
  49. /*  <ftp://ftpdev.info.apple.com//Developer_Services/
  50.      Technical_Documentation/PCI_Information/Designing_PCI_Cards_-_Driv.sit.>
  51. */
  52.  
  53. extern pascal SInt16 TradHigherDriverVersion(NumVersion *dv1, NumVersion *dv2);
  54.  
  55. extern pascal UnitNumber TradHighestUnitNumber(void);
  56.  
  57. extern pascal OSErr TradDriverGestaltOn(DriverRefNum refNum);
  58.  
  59. extern pascal OSErr TradDriverGestaltOff(DriverRefNum refNum);
  60.  
  61. extern pascal Boolean TradDriverGestaltIsOn(DriverFlags flags);
  62.  
  63. extern pascal OSErr TradLookupDrivers(UnitNumber beginningUnit,
  64.                                         UnitNumber endingUnit,
  65.                                         Boolean emptyUnits,
  66.                                         ItemCount *returnedRefNums, 
  67.                                         DriverRefNum *refNums);
  68.  
  69. ///////////////////////////////////////////////////////////////////////////
  70.  
  71. // The following routines are similar to the corresponding routines in
  72. //  DriverLoaderLib, but their interface differs because of the
  73. //  inherent differences between 'DRVR's and 'ndrv's.  The comments
  74. //  cover the differences for each routine.  If there's a difference
  75. //  that's not commented, it's most probably a bug and you should let
  76. //  me know.
  77.  
  78. extern pascal OSErr TradInstallDriverFromPtr(DRVRHeaderPtr driver,
  79.                                                 UnitNumber beginningUnit,
  80.                                                 UnitNumber endingUnit,
  81.                                                 DriverRefNum *refNum);
  82.     // This routine is similar to InstallDriverFromMemory except
  83.     //  that you pass a pointer to the 'DRVR', rather than a base pointer
  84.     //  and length.  This pointer is copied verbatim into the dCtlDriver
  85.     //  field of the DCE, so you have to make sure that it's in
  86.     //  the system heap if the driver is going to hang around longer than
  87.     //  your application.
  88.     // One other deviation from InstallDriverFromMemory is that this
  89.     //  call won't replace an existing driver.  This is because 'DRVR's
  90.     //  don't have infrastructure to support this.  If there's already
  91.     //  a driver of the same name in the unit table, the call will fail
  92.     //  with a dupFNErr, and *refNum will be set to the refnum of the
  93.     //  existing driver.
  94.     // The semantics of the endingUnit match those of DriverLoaderLib,
  95.     //  ie the call will not grow the unit table unless endingUnit is
  96.     //  greater than TradHighestUnitNumber.  The simplest way to work
  97.     //  this is to pass TradHighestUnitNumber() + 1 to endingUnit.
  98.     // If the call fails, it's your responsibility to dispose of the
  99.     //  the driver pointer.  If it succeeds, the system has a copy
  100.     //  of the pointer, which can be disposed by calling TradRemoveDriver.
  101.  
  102. extern pascal OSErr TradInstallDriverFromHandle(DRVRHeaderHandle driver,
  103.                                                 UnitNumber beginningUnit,
  104.                                                 UnitNumber endingUnit,
  105.                                                 DriverRefNum *refNum);
  106.     // This routine is similar to InstallDriverFromMemory except
  107.     //  that you pass a handle to the 'DRVR', rather than a base pointer
  108.     //  and length.  This is generally more convenient in the traditional
  109.     //  'DRVR' world.
  110.     // In most other respects, this routine works like TradInstallDriverFromPtr.
  111.     //  The routine simply creates a pointer in the system heap and copies
  112.     //  your driver into it, then calls TradInstallDriverFromPtr.  Because
  113.     //  a copy is made, you do not have to ensure that the handle you
  114.     //  pass in is in the system heap.
  115.     // Regardless of whether call succeeds or fails, it's your responsibility
  116.     //  to dispose of the driver handle.
  117.     
  118. extern pascal OSErr TradInstallDriverFromResource(SInt16 rsrcID, StringPtr rsrcName,
  119.                                                 UnitNumber beginningUnit,
  120.                                                 UnitNumber endingUnit,
  121.                                                 DriverRefNum *refNum);
  122.     // This call offers functionality like InstallDriverFromFile.
  123.     //  It differs from InstallDriverFromFile in that the driver is expected
  124.     //  to be in a resource in the current resource file.  If rsrcName is nil,
  125.     //  the call uses Get1Resource('DRVR', rsrcID) to get the driver.  If
  126.     //  rsrcName is not nil, it uses Get1NamedResource('DRVR', rsrcName)
  127.     //  to get the driver.
  128.     // In most other respects, this routine works like TradInstallDriverFromPtr.
  129.     // If the call fails, the routine will clean up after itself.  If the
  130.     //  call succeeds, the driver code is left as a memory block in the system
  131.     //  heap, which can be cleaned up by calling TradRemoveDriver.
  132.  
  133. extern pascal OSErr TradGetDriverInformation(DriverRefNum refNum,
  134.                                                 UnitNumber *thisUnit,
  135.                                                 DriverFlags *flags,
  136.                                                 StringPtr name,
  137.                                                 DRVRHeaderPtr *driverHeader
  138.                                                 );
  139.     // This routine is like GetDriverInformation except that it only
  140.     //  returns information that's pertinant to the traditional 'DRVR'
  141.     //  world.  driverHeader comes back as a pointer to the beginning
  142.     //  of the 'DRVR' header.
  143.     // Note that this routine works for both drivers installed by
  144.     //  this library and other drivers, however for drivers not installed
  145.     //  by this library (ie 'RAM'-based drivers), driverHeader may be a 
  146.     //  half dereferenced handle, locked or unlocked.  You have been warned.
  147.     // Also, driverHeader can come back set to nil, if the driver
  148.     //  is installed but its code has been purged, for example a DA.
  149.     //  You must check for this before deferencing it.  If driverHeader
  150.     //  is set to nil, name will be set to the empty string.
  151.  
  152. extern pascal OSErr TradOpenInstalledDriver(DriverRefNum refNum, SInt8 ioPermission);
  153.     // This routine has the same semantics as OpenInstalledDriver
  154.     //  except that the ioPermission parameter must be fsRdWrPerm.  This is
  155.     //  because we call through to the Device Manager's OpenDriver routine,
  156.     //  and that doesn't support passing in permissions.  I could switch the
  157.     //  implementation to use PBOpen, but PBOpen is a trap fraught with much
  158.     //  danger, so I'm avoiding it at the moment.
  159.     // The danger associated with PBOpen is that it's highly overloaded,
  160.     //  being used for FSOpen, PBOpen, PBHOpen, OpenSlot, OpenDriver,
  161.     //  OpenDeskAcc, and so on.  If you get the glue wrong, you die in
  162.     //  strange and evil ways.  So I'm bypassing the entire problem by
  163.     //  ignoring ioPermission.  I may revisit this decision, but not soon.
  164.  
  165. extern pascal OSErr TradRemoveDriver(DriverRefNum refNum, Boolean immediate);
  166.     // This routine implements similar semantics to RemoveDriver, except
  167.     //  that the Immediate parameter must be false.  This is because
  168.     //  we close the driver using PBCloseSync, which is a queued
  169.     //  command, just like all the others.  We have no way to bypass
  170.     //  this.
  171.     // An important thing to note is that you should only call this on drivers
  172.     //  you installed using this library's TradInstallDriverFromHandle
  173.     //  and TradInstallDriverFromResource routine.  Don't call it on
  174.     //  drivers installed by other people and be careful when calling it on
  175.     //  drivers installed using TradInstallDriverFromPtr because you might
  176.     //  be disposing the driver code even though a) it might not actually be a
  177.     //  Memory Manager pointer block, or b) it might be still in use
  178.     //  by another driver.
  179.  
  180. extern pascal OSErr TradRenameDriver(DriverRefNum refNum, ConstStr255Param newDriverName);
  181.     // This routine is implemented with the caveat that you can't
  182.     //  make the driver name longer.  This is because the 'DRVR'
  183.     //  name is actually stored in the code resource which implements
  184.     //  the driver, and making it longer would cause it to run into
  185.     //  the code that immediately follows the name.
  186.     // The reason why I implemented this routine at all is because
  187.     //  it's useful for installing multiple copies of the same driver.
  188.     //  For example, you can install ".Q_Out", then rename it to
  189.     //  ".QAOut", and then install ".Q_Out" again, and rename that to
  190.     //  ".QBOut".  This can be very useful when testing and debugging
  191.     //  your driver (or TradDriverLoaderLib for that matter :).
  192.     // You should take extreme care when calling this routine on drivers that
  193.     //  weren't installed with this library.  Some of these drivers might
  194.     //  not like being renamed in this way.
  195.  
  196. ///////////////////////////////////////////////////////////////////////////
  197.  
  198. // The following routines from DriverLoaderLib were not implemented because
  199. //  they make no sense at all in the world of 'DRVR's.
  200.  
  201. // VerifyFragmentAsDriver
  202. // GetDriverMemoryFragment
  203. // GetDriverDiskFragment
  204. // InstallDriverFromFragment
  205. // SetDriverClosureMemory
  206. // -- If they've got fragment in the name, it's hard to map them into the
  207. // 'DRVR' world.  Traditional 'DRVR's just aren't code fragments!
  208.  
  209. // InstallDriverFromFile -- This routine assumes that there's only
  210. //    one driver in a file, which is not the case for traditional 'DRVR's
  211. //  which are normally stored as resources.  The basic functionality has
  212. //  been subsumed by TradInstallDriverFromResource.
  213.  
  214. // InstallDriverFromDisk
  215. // FindDriversForDevice
  216. // FindDriverCandidates
  217. // ScanDriverCandidates
  218. // GetDriverForDevice
  219. // InstallDriverForDevice
  220. // -- These routines all assume that there's some magic way of matching
  221. //  drivers to their name register nodes.  In the traditional world, there
  222. //  is no name registry and, even if there was, there's no way to match
  223. //  devices against hardware.  So these routines are not sensible in the
  224. //  traditional world. 
  225.  
  226. // ReplaceDriverWithFragment -- There's no good way to replace a traditional
  227. //  device driver; the infrastructure just isn't there.
  228.  
  229. #ifdef __cplusplus
  230. }
  231. #endif
  232.